For iOS < 26 there is no style set explicitly here; maybe, to be consistent, we should set it to something? And please mention the difference for iOS versions somewhere in the docs.

I don't think we need to set it to something else on iOS < 26. I believe it's better to leave it untouched and use the default style of the OS when the prominent style is not available. UIBarButtonItemStylePlain is the default style of iOS < 26.

And about docs, I'm linking to the Apple docs in the JSDoc comments in the type declaration. I'm also mentioning that "Prominent" is only available on iOS 26. https://github.com/johankasperi/react-navigation/blob/668b77545440c51f473bf7e392a6b8b946eec8f9/packages/native-stack/src/types.tsx#L729

Could you point me to where in the docs I should also mention this?

One could also argue that linking to the iOS docs is sufficient, especially during the beta period when stuff might be changed by Apple, since by trying to copy Apples docs to the React Native Screen docs the RNS docs might become dated quickly when Apple are doing changes. But I'm not gonna be the judge of that 😊

In this case we should add some documentation to src/types.tsx, maybe also to GUIDE_FOR_LIBRARY_AUTHORS, especially the different cases when the behavior is different for iOS 26 vs 18. I saw there is more documentation in the PR for react-navigation, but it would be nice to have it also here in screens.

Do you mean this interface?

And in GUIDE_FOR_LIBRARY_AUTHORS, do you mean I should add it under this section? https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md#screenstackheaderconfig

That's what I was thinking about, It'd be good to have something in the same place where other screens components' props are defined for quick reference when someone new jumps in. IN GUIDE... there is this section "Below is a list of properties that can be set with ScreenStackHeaderConfig component:" and since you are adding new props, we should keep it in sync & write something there. Same for src/types.tsx.

Thansk for pointing me to where I should write something. I will do that asap

Added the types in this commit 3e2f63d

Added docs in this commit b41acf8

Not sure what it means exactly yet, but we need to make sure that this PR does not modify currently existing API in breaking manner.

(TODO: revisit this comment after full review)

It doesn't modify existing API. It adds to the existing API by giving the opportunity to render a < BarButtonItemCustomView> (that has the prop hidesSharedBackground ) as a direct child to ScreenStackHeaderRightView or ScreenStackHeaderLeftView

If you look at my PR to react-navigation/native-stack I've added a BarButtonitemCustomView as direct child when rendering headerLeftItems/headerRightItems React Elements but not when rendering the existing headerLeftElement/headerRightElement. So it is optional https://github.com/johankasperi/react-navigation/blob/a79b931cfd1c4507db4ff794a0fe8f30579b439b/packages/native-stack/src/views/useHeaderConfigProps.tsx#L331

I don't see a reason for this prop to not live directly on the header subview components. Why complicate it here?

What do you think?

That was my initial thought but decided not to do that because the native RNSScreenStackHeaderSubview is used by more subviews than header left/right (center/title and search bar). And the hidesSharedBackground prop would have been obsolete and no effect on them. And as I said earlier I took inspiration from how RNSSearchBar was created and used, as a direct child to the RNSScreenStackHeaderSubview. So I think my implementation follows the existing API design/structure.

I see your point referring to the search bar here. I dislike distinguishing "custom subview" type from the rest of the API, however. Until now a way to render a custom view inside a header was to wrap it with ScreenStackHeaderSubview{Left,Rigth,Center} component. Most likely search bar was treated special, because it was a fully native view, w/o any react views inside, managed by the native side. Right now, we would create new way to render a custom view, IMO unnecessarily creating new ways of doing it. While I get that the hidesSharedBackground prop will not apply to all the possible contents I still think that its better way to go. Please note, that e.g. you could render SearchBar inside BarButtonInCustomView and still misuse the API, possibly breaking searchbar.
I want the hidesSharedBackgroundProp to live directly on header subview. In context where its application does not make sense - it should be a noop.

I feel like we could bikeshed here for a long time, therefore let's settle with putting in on ScreenStackHeaderSubview.

Awesome! Thanks for taking a clear decision on the matter and guiding me forward. It's not like I have a strong opinion on the matter and I totally respect that you have way more understanding of the entire lib than I have. In my previous response I just wanted explain why I designed it like I did and my thought process. I will add hidesSharedBackground directly to ScreenStackHeaderSubview asap so we can put an end to this discussion 😄

I have now moved the hidesSharedBackground to ScreenStackHeaderSubview in this commit b8a0164

I removed the CustomViewBarButtonItem in this commit 96c9846

Great, thanks!

Also:

I understand that this prop allows to hide the background from header items created via already existing API, not the one this PR adds.

I like this change & I'm for it. But this should really be done in separate PR.

Keep this at low priority though. I'll let is slip if we're ready with rest of the PR.

#2987 (comment)

I doesn't break the existing API but the BarButtonItemCustomView component was needed to hide the glass effect background on bar button items with a custom view/React Element.

I totally get that this should have been done in a separate PR. Sorry about that

If I understand this section correctly (have not read the rest of the recent changes yet), it introduces API to modify header items achievable with currently existing API.

While I like this idea, it should not be in this PR. Treat is as low prio though. If we sort out the rest of the PR I'll let it slip 😄

Can I ask for a bit of explanation why is the setter deferred here?

Isn't setHidesSharedBackground run on the JS thread (using old arch) but changing the visuals of the UIBarButtonitem need to be done on the main thread

Tried to verify this when running examples app with old arch. setHidesSharedBackground is running on the main thread so no need to dispatch to it. Pretty sure I saw a crash here before but must have misunderstood it. Remove it here 2ecc9cf

Thanks for verifying it. The mounting stage code (including prop updates) on both archs should be confined to UI thread, therefore we should be safe here.

I can navigate to this commit & see the changes, but when reviewing I still see the old code. Is this GitHub glitch or was this commit lose somewhere in rebase?

Weird. I will look into that asap

Must be a Github glitch because I'm not seeing the old code?

I dislike the approach here. We already create & initialise the button item in line 631. With introduction of RNSBarButtonItemCustomView we split part of the configuration to the child, which retains the bar button strongly, creating circular dependency, etc.

What about moving this prop directly onto header subview component & adding either:

1. small factory method that will take the subview & output nicely configured UIBarButtonItem for us,
2. or a subclass of UIBarButtonItem that will have initialiser ~ initWithHeaderSubview:(RNSScreenStackHeaderSubiew *) and will do nice configuration there.

The thing is with your suggestions the UIBarButtonItem will not be updated if the RNSScreenStackHeaderSubiew (or RNSBarButtonItemCustomView for that matter) props changes and rerenders. From what I understand we need to have a updateProps (for Fabric) and a reference to the existing UIBarButtonItem to change its props since it will not be recreated (as it was earlier when the configuration was part of the headerRightItems/headerLeftItems array).

What I'm considering now is ditching the idea of RNSBarButtonItemCustomView and go back to configuring the custom elements in the headerRightItems/headerLeftItems array. What do you think?

I refactored RNSBarButtonItemCustomView in 3ef0f53 and removed the circular dep.

I also created a small factory method in d93acd6

Please let me know if you like this idea with RNSBarButtonItemCustomView or if we should ditch it in favour of using config in the items array instead. I still think what I said in #2987 (comment) is valid. Using RNSBarButtonItemCustomView is more similar to how RNSSearchBar is implemented. Thank you!

Of course, the same remarks apply here.

ok, thanks!

Thanks for verifying it. The mounting stage code (including prop updates) on both archs should be confined to UI thread, therefore we should be safe here.

I can navigate to this commit & see the changes, but when reviewing I still see the old code. Is this GitHub glitch or was this commit lose somewhere in rebase?

I see your point referring to the search bar here. I dislike distinguishing "custom subview" type from the rest of the API, however. Until now a way to render a custom view inside a header was to wrap it with ScreenStackHeaderSubview{Left,Rigth,Center} component. Most likely search bar was treated special, because it was a fully native view, w/o any react views inside, managed by the native side. Right now, we would create new way to render a custom view, IMO unnecessarily creating new ways of doing it. While I get that the hidesSharedBackground prop will not apply to all the possible contents I still think that its better way to go. Please note, that e.g. you could render SearchBar inside BarButtonInCustomView and still misuse the API, possibly breaking searchbar.
I want the hidesSharedBackgroundProp to live directly on header subview. In context where its application does not make sense - it should be a noop.

I feel like we could bikeshed here for a long time, therefore let's settle with putting in on ScreenStackHeaderSubview.